# Плагины

**ВНИМАНИЕ:** Данный функционал находится на этапе beta-тестирования. С высокой вероятностью он будет модифицироваться.
Мы будем стараться сохранять совместимость при его развитии, но следует учитывать эту информацию 
при принятии решения об его использовании.

**ВНИМАНИЕ:** Плагины в настоящий момент поддерживаются только при развертывании DocHub в режиме портала. В плагинах IDE 
данный функционал пока не поддерживается. Но обязательно будет.

## Введение

Плагины это специально оформленные программные модули на JavaScript, с использованием фреймворка [VUEJS 2](https://ru.vuejs.org/v2/guide/index.html),
расширяющие функциональные возможности DocHub.

С их помощью можно создать:

1. Новый [тип документа](/docs/dochub.docs) - реализовано (beta);
2. [Источник данных](/docs/dochub.datasets) - запланировано.

## Создание простого плагина

В этом примере показано, как создать плагин, который расширит набор встроенных типов документов новым - "html".

Клонируйте репозиторий DocHub.

```bash
git clone https://github.com/RabotaRu/DocHub.git
```

Установите все зависимости.

```bash
cd DocHub
npm install
```

Создайте каталог, в котором вы будете разрабатывать свой код в специальной области проекта DocHub - ./plugins.
Например, каталог с именем "html".

```bash
cd plugins
mkdir html
cd html
```

В этом каталоге создайте следующие файлы:

* **components/HTMLDocument.vue** - VUE компонент, который будет визуализировать документ;
* **package.json** - Файл-манифест плагина;
* **index.js** - Точка входа плагина.

### package.json

Это стандартный файл, используемый Node.js для описания содержимого проекта.

Чтобы сгенерировать стандартный файл package.json, вы можете использовать команду:

```bash
npm init
```

При запуске этой команды вам будет задан ряд вопросов, чтобы помочь создать начальный контент для проекта. 
Многие вопросы имеют ответы по умолчанию. Используйте их там, где это возможно. 

При появлении запроса дать имя проекту, введите - "dochub-plugin-html".

Пример сформированного файла:
```json
{
  "name": "dochub-plugin-html",
  "version": "1.0.0",
  "description": "HTML document",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "R.Piontik",
  "license": "MIT"
}
```

### index.js

```JavaScript
import doc from './components/HTMLDocument.vue';

DocHub.documents.register('html', doc);
```

Точка входа это JavaScript модуль. Он запускается сразу при подключении.

Задачей точки входа является регистрация предоставляемых плагином функциональных возможностей.

В примере, для регистрации нового типа документа, используется специальный интерфейс [DocHub](/docs/dochub.plugins.interface).

После выполнения описанного в примере кода, в DocHub будет зарегистрирован новый тип документа "html". 
При указании этого типа документа, управление его рендерингом будет передаваться компоненту плагина.


### HTMLDocument.vue

Файл содержит [VUE2 компонент](https://ru.vuejs.org/v2/guide/components.html). Его задачей является
рендеринг данных архитектуры в соответствии с переданными ему параметрами в "profile".

```JavaScript
<template>
  <div v-html="content" />
</template>

<script>

  export default {
    name: 'HTMLDocument',
    props: {
      // Требуем обязательно передавать профайл документа 
      profile: {
        type: Object,
        required: true
      },
      // Требуем обязательно передавать функцию получения контента
      getContent: {
        type: Function,
        required: true
      }
    },
    data() {
      return {
        content: ''
      };
    },

    watch: {
      profile() {
        // При изменении параметров, перезагружаем контент документа с их учетом
        this.refresh();
      }
    },
    mounted() {
      // При монтировании компонента в DOM загружаем контент документа
      this.refresh();
    },
    methods: {
      // Функция обновления контента документа с учетом параметров содержащихся в "this.profile"
      refresh() {
        if (this.profile) {
          // В архитектурной кодовой базе указываются относительные пути к файлам при описании документа.
          // Для успешного получения контента этих файлов необходимо использовать функцию getContent.
          // Рекомендуется также использовать эту функцию для доступа к любым иным ресурсам по http/https. 
          this.getContent(this.profile.source)
            // Если все хорошо, рендерим HTML "как есть"
            .then((response) => {
              this.content = response.data;
            })
            // Если что-то пошло не так, генерируем HTML с ошибкой
            .catch((error) => {
              this.content = `<div style="color:#fff; background-color: #f00">Ошибка выполнения запроса [${this.profile.source}]: <br> ${error}</div>`;
            });
        } else this.content = '';
      }
    }
  };
</script>
```

Параметры "profile" и "getContent" является частью контракта [интерфейса ядра DocHub](/docs/dochub.plugins.interface). 

## Сборка

Плагин должен собираться в контексте проекта DocHub. Для этого, необходимо в файле ./plugins.json указать ссылку на его проект. 

```json
  {
    "inbuilt": [
      "plugins/html"
    ]
  }
```

Обратите внимание, что путь указывается **к папке** с проектом плагина. Сама папка должна располагаться **внутри** проекта DocHub. 
Рекомендуется использовать для этого папку ./plugins.

Теперь можно собрать проект DocHub в нескольких режимах:

### developing

Сборка осуществляется командой:
```bash
npm run serve
```

В результате сборки будет локально запущен dev сервер Node.js, который позволит отлаживать ваш проект.
После сборки информация о доступе к нему будет выведена в консоль и иметь вид:

```
  App running at:
  - Local:   http://localhost:8080/ 
  - Network: http://192.168.8.104:8080/
```

Данный режим предназначен для разработки плагинов. Он позволяет вносить изменения в кодовую базу и в режиме 
реального времени (без пересборки) наблюдать результат изменений.

### production

Сборка осуществляется командой:
```bash
npm run build
```

В результате сборки, плагин будет встроен в поставку. Располагаться скомпилированный плагин будет в папке ./dist/plugins.

## Использование

После сборки проекта DocHub с плагином, достаточно указать необходимый тип документа в коде архитектуры и передать 
плагину информацию о файле контекста. Сделать это можно так:

```
docs:
...
  dochub.plugins.example:
    location: DocHub/Руководство/Плагины/Примеры/HTML
    type: html
    source: examples/example.html
```

В поле "type" указывается новый тип документа "html" зарегистрированный плагином. 
В поле "source" указывается относительный путь к файлу, содержащему HTML код.

Содержимое файла "examples/example.html":

```

<H1>Привет!</H1>
<P>Это простейший пример HTML-документа, который выводится с использованием плагина DocHub.</P>
```

Работу примера можно посмотреть [здесь](http://localhost:8080/docs/dochub.plugins.example).

Полный исходный код примера можно найти [тут](https://github.com/RabotaRu/DocHub/tree/master/plugins/html).

## Встраивание объектов DocHub в представления плагина

Для встраивания объектов DocHub в представления используйте специальный VUE компонент "dochub-object":

```
<dochub-object src="@document/dochub.example.swgr" />
```

Параметры для встраиваемого объекта передаются как GET параметры URL в поле "src". Например:

```
<dochub-object src="@entity/interactions/blank?id=dochub.user.research" />
```

В данном примере в представление плагина встраивается сущность "interactions" с использованием 
презентации "blank" и параметром "id" со значением "dochub.user.research".